<?php
namespace db;

use IteratorAggregate;
use Countable;

/**
 * Query result that holds the result data (or will fetch it when necessary silently).
 * It has a set of methods that will help you to sepcify the format of data that you want to get.
 *
 * Some of methods returns independent data but some don't, so when you modify it, its likely that
 * other returned data will be modified too. You should be aware of that when you are modifying it.
 *
 * It can be iterated in foreach loops like arrays, or used as argument of count() function.
 *
 * @author Jakub Dykowski
 *        
 */
interface QueryResult extends IteratorAggregate, Countable {

	/**
	 *
	 * @return array of \ArrayObject
	 */
	function many();

	/**
	 * 
	 * @return number of rows in result
	 */
	function count();

	/**
	 *
	 * @return bool whether the result is empty
	 */
	function isEmpty();

	/**
	 * Returns the result as one.
	 *
	 * @return ArrayObject or null
	 * @throws \Exception if there is more result
	 */
	function one();

	/**
	 * Returns first or speciefied field from the only result.
	 *
	 * @param string $name
	 *        	field name
	 * @throws \Exception if result is empty
	 * @return string
	 */
	function field($name = null);

	/**
	 * Returns assoc array (of key-value pairs).
	 *
	 * @param string $key
	 *        	field to be used as key
	 * @param string $value
	 *        	field to be used as value
	 * @return array
	 */
	function keyValue($key, $value);

	/**
	 * Groups the result by given arguments(fields) where that field will be key and the
	 * value will be an array of results with the same given field.
	 *
	 * @param vararg $by,... unlimited number of fields to group by
	 * @return array grouped results with key as grouped value
	 * @throws \InvalidArgumentException if arguments are less than 1 or field is not found in any result
	 */
	function group($by);

	/**
	 *
	 * @return int newly created row id
	 * @throws Exception if primary key is not autoimcrement
	 */
	function id();
}